Implements docs/superpowers/plans/2026-07-24-t3x-auto-build-desktop-plan.md.

Rebuilds the macOS arm64 .dmg when HEAD moves to a new commit and can install
it into /Applications, so the installed app tracks the fork automatically.

- scripts/t3x/auto-build-desktop.sh — one-shot build (SHA-keyed idempotency),
  --install (mount/replace/quarantine-strip), --relaunch, --watch (polls HEAD,
  re-execs under caffeinate, never crashes the loop), --dry-run, --force,
  --print-launchd (emits a valid LaunchAgent plist with real paths).
- scripts/t3x/hooks/post-merge — opt-in hook, never auto-installed.
- docs/t3x/auto-build-runbook.md — runbook incl. the channel caveat below.

Trigger is a new commit SHA, not file saves: a dmg build takes minutes, so
watching raw writes would rebuild continuously mid-edit. The last-built marker
advances only on success, so a failed build retries next poll.

Zero upstream seams: shells out to the existing `pnpm dist:desktop:dmg:arm64`
rather than editing scripts/build-desktop-artifact.ts, and adds no root
package.json script (both hot upstream files). Invoked by path.

Verified: --dry-run is side-effect free; --print-launchd passes `plutil -lint`.
Noted in the runbook: a local build is the stable channel ("T3 Code.app") while
this machine runs "T3 Code (Alpha)/(Nightly).app", so --install would create a
third app rather than update those — the user must pick a target deliberately.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Fixes from the review pass on PR #1. The first one invalidated a claim the PR
made about itself.

1. `--install --dry-run` actually quit the running app. `osascript -e 'quit app'`
   sat ABOVE the dry-run early return, so a dry run — which the PR advertised as
   "side-effect free" — would close the user's app. It only looked clean when
   tested here because the app it targets ("T3 Code") is not the channel running
   on this machine, so the quit was a silent no-op. Moved below the return; the
   dry run now logs "would: quit app" instead.

2. A relative `T3CODE_DESKTOP_OUTPUT_DIR` was read literally, while
   build-desktop-artifact.ts resolves it with `path.resolve(repoRoot, …)`.
   `T3CODE_DESKTOP_OUTPUT_DIR=artifacts` therefore searched the caller's
   ./artifacts and reported "no .dmg" for a build that had succeeded. Relative
   values now resolve against $REPO; absolute ones are untouched.

3. Plist values were not XML-escaped. A repo path containing & or < (legal on
   macOS) emitted a malformed plist that launchctl silently refuses to load.

4. `--interval` accepted 0, negatives and non-numerics: 0 turns the poll into a
   tight rebuild loop, and a non-numeric makes `sleep` fail and kills the
   watcher. Now validated at parse time.

5. `pnpm install` / `ensure:electron` failures were ignored in watch mode. bash
   disables errexit for the whole dynamic extent of a function whose status is
   tested, and the watcher calls `if ! build_once`, so a failed install fell
   through and the dmg was built against stale dependencies. Both are now
   checked explicitly.

6. A failed `cp` into /Applications was reported as a successful install, and a
   failed install still advanced the SHA marker — so the next poll said "no
   change" while /Applications held the old app and the failure was never
   retried. The marker now means "built AND installed, if an install was asked
   for", and a failed install writes an "install-failed" status.

Verified: dry-run leaves the status file untouched and only logs the quit;
interval rejects 0/-5/abc; a relative output dir resolves to <repo>/release; the
emitted plist still passes `plutil -lint` and escaping handles `&` and `<`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Second review pass, run against a real harness (pnpm shim, osascript spy, real
dmg) on bash 3.2.57 — the version macOS actually ships. Two were critical.

CRITICAL
1. `--watch` with no other flag died before its first poll. `"${extra[@]}"` on an
   EMPTY array is an unbound-variable error under `set -u` on bash < 4.4. Because
   `--print-launchd` emits no KeepAlive, the LaunchAgent it generates therefore
   started, died in under a second, and was never retried — the hands-off path
   silently never worked at all.

2. `--watch --install --dry-run` performed a REAL build and a REAL install. The
   caffeinate re-exec forwarded only 4 flags and dropped --dry-run/--force, so
   the re-exec'd process ran with DRY_RUN=0: it quit the running app, rm -rf'd
   the target and replaced it — from the exact command someone runs to preview
   the watcher. Both fixed by rebuilding the full flag set (seeded non-empty,
   which also removes the empty-array hazard).

MAJOR
3. Install now stages beside the target and swaps. BSD `cp -R src.app dst.app`
   copies INTO dst.app when it still exists, so an unremovable target (root-owned
   or locked) silently nested the new build inside the old one and exited 0 —
   logged "replaced", advanced the marker, and left the user on the old app
   forever. Deleting before copying was also unsafe: a mid-copy failure left no
   working app at all.
4. `"installed"` was derived from the flags, emitting
   {"result":"install-failed", …, "installed":true}. Now reflects the outcome.
5. `--print-launchd` derived its paths from env overrides but propagated none of
   them, so generating a plist from a shell that had redirected
   T3X_AUTOBUILD_APPLICATIONS_DIR to a temp dir for testing produced an agent
   that wrote to the REAL /Applications. All four vars are now emitted.
6. Repeated failures back off (2x…32x, capped at 30 min). Previously a persistent
   fault meant a full multi-minute rebuild every 60s indefinitely.
7. Added a lock. hooks/post-merge nohups a build on every merge, so two quick
   pulls ran two concurrent electron-builder runs against one output dir, and one
   could rm -rf the install target mid-copy of the other. Stale locks are cleared.
8. Both documented git-hook install methods were broken: this repo sets
   core.hooksPath=.vite-hooks/_, so `git config core.hooksPath scripts/t3x/hooks`
   would DISABLE every existing hook and the .git/hooks symlink would never fire.
   Documented the real mechanism (.vite-hooks/<name>) and steered toward the
   watcher/LaunchAgent instead.

MINOR
9. T3X_AUTOBUILD_KEEP_DMGS is validated: non-numeric made `tail -n +$((…))`
   evaluate to 1 and prune EVERY dmg including the one just built, and `$(( ))`
   on that input is a command-execution sink (verified, now blocked).
10. prune_dmgs returns 0 explicitly — its trailing `rm` status could abort the
    script with exit 1 after a fully successful build had already been recorded.
11. Runbook corrections: rapid commits do NOT collapse cleanly (a commit landing
    mid-build causes one redundant rebuild); pruning covers *.dmg only, while
    each build also leaves a ~233MB .zip that accumulates forever; documented
    exit code 2 and clarified T3X_AUTOBUILD_APP_NAME is dry-run only.

Verified on bash 3.2.57: `--watch` alone stays alive; `--watch --install
--dry-run` logs 18 DRY-RUN lines with 0 real builds and writes no state; the lock
skips a second instance; interval and keep-dmgs guards reject bad input with no
injection; the plist passes plutil -lint and carries the env overrides.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The runbook claimed a plain local build produces `T3 Code.app` and would
therefore create a third app alongside an Alpha/Nightly install. Verified
against the actual artifact: `resolveDesktopProductName()` falls back to
`"T3 Code"` only when `apps/desktop/package.json` has no productName, and
upstream sets it to `"T3 Code (Alpha)"`. Mounting the built dmg confirms it
contains `T3 Code (Alpha).app`, so a default `--install` replaces the Alpha
app most fork users already run.

Replaces the prose with the version -> channel -> .app mapping and a copy-paste
check that reads the name out of the dmg instead of trusting the doc.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>